****************** Welcome to SHAZAM! ****************** Documentation for SHAZAM is both "online" and "offline": [X] ONLINE - The context-sensitive portion is cross-referenced with the manual, most of which is also in HyperText format. [X] OFFLINE - The PRINTDOC program is about to be generated and compiled. It will print the Technical Manual and demonstration programs with your choice of formats and margins. The "Test print" option is a 2-page report, so you can make adjustments and try different settings. All source for units and example programs is included. You can re-use dialogs, hints and help text files as "plug n' play" elements of your own programs. CONTENTS -------- 1 - Getting started 2 - Notes 3 - Installation 4 - Units 5 - Examples 6 - Overview 7 - Acknowledgements 8 - Technical Support 1 - GETTING STARTED =================== If you are upgrading from version 1.x, you MUST read UPGRADE.DOC. To give you an idea of what SHAZAM can do, the following... KEYWORDS & ITEMS HINTS | | V V ---------------------------------------------- [ submenu ] file ;;hint for file stuff open f3 ;;open a file save f2 ;;save window [ status ] f1 Help ;;call HyperText help alt-x exit cmQuit ;;return to DOS ---------------------------------------------- ...creates a ready-to-run EXE with Help Text & Hints, using overlays and resources, recovers overlay heap for EXEC, and runs under DOS 2.x or higher. By default, SHAZAM allows for use of ExecSWAP, so the application is unitized (encapsulated) and you get Swap-To-Disk/EMS capability too, with minimum overhead, less than <6k. No kidding. Type the above into a file with an *.DEF extension & press Ctrl-F9. Don't want overlays? Use the "/O-" switch, from the DOS prompt or SETUP|Code dialog. No ExecSwap? Use "/X-". Code, instead of resources? Use "/1". And so on... Now, for an actual "Exec", you would have to add custom code, BUT there's a routine in GENERAL.PAS called "VisionExec" (just like DOS.Exec) which takes care of Turbo Vision housekeeping for you. There's also pre-done events called "hdLittleDOS", "hdMediumDOS" and "hdBigDOS" for shelling to the DOS prompt. Run the ED*.DEF examples and see the help text for details. The basic idea of using SHAZAM is: It codes the "FrameWork" for you, so you can concentrate on "fleshing out" custom code and Help Text. This gives you the freedom to experiment with interface design, since you can re-generate & re-compile anytime with one keystroke (Ctrl-F9). To accelerate your learning curve --------------------------------- Start with the ADEMO*.DEF series, in IDE mode. Type "C:>shazam", use "File|OPEN" to select a file, then press Ctrl-F9, which will generate, compile & run a program. An alternative -------------- Print the ADEMO*.DEF series, then generate all programs using command-line mode. Type "C:>shazam ademo*/m" to generate, compile & run the whole series at once. Note on HELP ------------ SHAZAM generated programs will automatically support ALT-F1 (to view previous help screens) if you patch HELPFILE.PAS with ALTF1.PAT 2 - NOTES ========= [X] Copyrights Please respect any and all copyright notices. All parts of this software are copyrighted, including but not limited to programs, documentation, source-code and examples. As a licensed user, you may use the example programs. However, they may not be sold, given away or otherwise distributed without written permission. Also, as a licensed user, you are free to incorporate examples (definitions, help text, etc.) and source code into your programs. [X] Documentation You should view, or print, all *.DOC files. Do AINTRO.DOC first, before starting on the ADEMO*.DEF series. You may also want to print the ADEMO*.DEF files as you go along. Since SHAZAM automatically loads support files along with definitions, you can use "File|Print all" or Ctrl-F4 to print all editor windows currently loaded into the Desktop. [X] Interactive and Command-Line modes Both are supported in the same program. Type "C:\>shazam /?" at the command-line for a list of switches, or "C:\shazam" and select the SETUP|Code dialog. [X] PATCHES A number of tested patches have been included. Browse the *.PAT files for details. APP.PAT - DesqView patch for APP.PAS ------------------------------------ If you want all your Turbo Vision programs to run under DesqView, APP.PAT contains a simple modification to accomplish this. If you make this patch, activate the "define" in the "COMPILER.PAS" file by adding a dollar sign: {DEFINE desqview} --> {$DEFINE desqview} This is so the "UserScreen" and "CopyScreen" routines in GENERAL.PAS will recognize the DesqView patch. EDLOAD.PAT - for original EDITORS --------------------------------- An improved version of EDITORS comes with SHAZAM. If you want to use the original, you must correct this bug in the load/store methods, or your program will hang during Desktop load/store. [X] ONLINE HELP SHAZAM comes with its own help file, but if you need Online Help for Turbo Vision, don't forget THELP.COM (shipped with Turbo Pascal). It provides memory resident help/reference on both Turbo Pascal & Turbo Vision at a relatively low cost in memory overhead (about 30k). 3 - INSTALLATION ================ If you need to restore the example code, you can re-run INSTALL. All existing files will be over-written. Programs -------- INSTALL.EXE - Installation program INSTALL.DAT - Installation data Archives -------- BABEL - Multiple Language Editor DEF - Commonly used Definitions DLG - Commonly used Dialogs EXAMPLES - Sample definitions and source code EXSWAP - Source code for EXECSWAP & EXECPROC GENERAL - General purpose code for Turbo Vision PATCH - Turbo Vision patches SHAZAM - Program, Help and Help Compiler TXT - Commonly used Help Text Instant INSTALL --------------- Installation was done using "Instant INSTALL", a generic INSTALL program which supports multiple diskettes using ARC/LZH/ZIP formats and de-archive programs. For more information, use the "/?" switch at the DOS prompt: C:\>a:install/? SHAZAM program installation creates the following directory structure: ?:\SHAZAM2\ \DEF\ \DLG\ \TXT\ You are free to re-arrange things to suit you. Use the SETUP | Directory dialog to let SHAZAM know where things are. The most likely change is to move the program files -- SHAZAM.EXE, SHAZAM.HLP and SZHC.EXE -- to a directory on your system PATH. DISK SPACE ---------- Although three megabytes of disk space are needed to install SHAZAM and run the PRINTDOC program, you can erase the examples and keep only the program files. To free up disk space (ie: before a backup), run CLEAN.BAT. This erases only generated files, which you can easily re-create. PORTABLE SHAZAM --------------- If you must work "on-site" to develop an interface, it is possible to fit SHAZAM, the compiler (TPC.EXE) and the Turbo Vision units on a high-density diskette of either size. The bare essentials are: [X] SHAZAM.EXE - main program. (SHAZAM.HLP is optional) [X] SZHC.EXE - new Help Compiler (old TVHC.EXE may be used) ...plus the compiler and TV units, of course. 4 - UNITS ========= Only the Turbo Vision units are needed to compile a generated application. However, a number of utility & workhorse units are included, as used by SHAZAM itself and many of the examples: GENERAL.PAS Standard events, dialog handling, strings, conversion and so on. Routines such as "hdSaveDesktop", "hdLoadDesktop", "VisionExec", etc. may be called within any Turbo Vision application. PRINT.PAS Report & print capability for Turbo Vision or DOS, with support for Generic, Dot-Matrix, LaserJet and DaisyWheel printers. Interruptible dialogs are easy to use, can print to disk or LPT ports, and are ready for use with EditWindows, printing from disk files, from the FileViewer or other PCollections (see PPRINT.INT). For user control of printing, the library directories contain re-usable dialogs, hints and help text for page & printer setup (PAGE.DLG & PRINT.DLG, HINTPRN.DEF, PRNSETUP.TXT). EDITORS.PAS An enhancement of the original EDITORS, providing the following features via direct keystrokes and/or from a menu: * Centering * Right-margin * Go to line number * TAB stops * Place markers (10 per window) * Word wrap Several *.DEF, *.DLG and *.TXT files were created to enhance this unit. Actually, you have everything used by this version of SHAZAM. See ED*.DEF for examples, EDITORS.DOC for unit details. EXECSWAP.PAS & EXECPROC.PAS These provide swap-to-disk/EMS for EXEC calls. Note that using "VisionExec" in place of "DOS.Exec" takes care of TV house-keeping as well. See the EXEC*.DOC files for details, ADEMO9.DEF for example. LISTREZ.PAS Program to list contents of resource files (*.REZ). 5 - EXAMPLES ============ The example definitions will generate as either code or resource based programs. For those examples which switch MenuBars/Boxes and StatusLines, compiler symbols are used in program logic. If ALL framework/interface elements are either code OR resources (but not a mix), SHAZAM automatically defines the compiler symbols "code" or "resource", respectively. If you use mixed options, be forewarned that this may affect the program logic in the examples. 6 - OVERVIEW ============ SHAZAM generates complete TApplications, including Help Text and Hints, so you can test the look & feel of your visual shell. You can generate, compile and run directly from SHAZAM. The Help Compiler and Code Compiler are called as needed. The Turbo Vision objects provide you with a set of "bones", around which you add the "meat" of your application. With SHAZAM, you change the skeleton to make different animals. This lets you concentrate on "fleshing out" your program, rather than writing and debugging user-interface code. (OK, OK, enough with the analogies already...) COMPOSING AN INTERFACE MenuBars, MenuBoxes, StatusLines and Hints are composed one line at a time, in a definition (*.DEF) file. In most cases, you need only two or three of SHAZAM's keywords. In addition, you can design dialogs interactively using the built-in Dialog Editor (Alt-D). There aren't many limits to what you can do. As you work through the examples, bear in mind that SHAZAM was used to design itself; as well as compile, overlay, execswap, etc. It's just a tad easier than hand-coding...and you can re-use what you create in other programs. Especially since include files can be nested for both definitions and help text. The ADEMO*.DEF series shows how to travel the road from interface to working program. It might be handy to use the PRINTDOC program to extract a Table of Contents and/or just the documentation from all example *.DEF files. MAKE IT A PROGRAM One use of SHAZAM is to create, revise and experiment with user interfaces. But you can maintain software with it, too. With SHAZAM's "scanning" ability and the [ EXTERNAL ] keyword, you can easily add methods and events from include files and units. You can quickly develop and change interfaces, using just code and no online help. Or you can maintain fully resourced, overlaid programs with HyperText Help and Hint Text, using switchable MenuBars/Boxes, StatusLines and Hint sets. Foreign translations are also made easier: See the BABEL example. One thing to keep in mind: SHAZAM maintains and regenerates itself, and it was built from the Turbo Vision and GENERAL units. DESIGN PHILOSOPHY Although some of the examples use code from the GENERAL, PRINT and EXEC*.PAS units, code generated by SHAZAM requires only the standard Turbo Vision units. No dependencies are introduced, with the exception of ExecSWAP, and that can be turned off ("/x-" switch). 7 - ACKNOWLEDGEMENTS ==================== EXECSWAP -------- This source-code is by Turbo Power Software and is included by permission. The company has a forum library on CompuServe (PCVENB) and has other programming products. They may be contacted by: Kim Kokkonen Information 719.260.6641 TURBO POWER SOFTWARE Orders 800.333.4160 Post Office Box 49009 Fax 719.260.7151 Colorado Springs, CO 80949-9009 CompuServe 76004.2611 USA INTERNET 76004.2611@compuserve.com DIALOG EDITOR ------------- The built-in Dialog Editor was derived by permission from L. David Baldwin's original DLGDSN (Dialogbox Design). It will read and export the *.DLG file format. EDITORS ------- This unit is adapted from Al Andersen's original NEWEDIT package, by permission. BABEL Multi-Language Editor --------------------------- The translations for the definitions (*.DEF) and help text (*.TXT) were done by: Thomas Davidson PASO del NORTE LENGUAJE Voice 915.564.0990 2713 Hamilton Ave Fax 915.564.5293 El Paso, TX 79930-3639 CompuServe 75540.1022 USA INTERNET 75540.1022@compuserve.com Note - Work was done via CompuServe EMAIL. 8 - TECHNICAL SUPPORT ===================== If you have any problems, you can get the best Technical Support by Electronic Mail or telephone. For subjects of a more leisurely nature, you can send postal mail. Johnathan J. Stein STEIN RESEARCH & ENGINEERING Voice 419.666.7103 Post Office Box 346 Fax 419.874.4922 Perrysburg, OH 43552 CompuServe 76576.470 USA INTERNET 76576.470@compuserve.com {/////////////////////////////////////////////////////////////////// // THE END // //////////////////////////////////////////////////////////////////// // // // First, there was SHAZAM I: "To TAME TApplication!" // // Then came SHAZAM II: "The WRATH of RESOURCES!" // //- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // // Next, our Hero returns in: // //- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // // // // SHAZAM III // // ---------- // // "The SEARCH for SERENDIPITY!" // // // //////////////////////////////////////////////////////////////////// // Advance tickets sent to Licensed Users // ///////////////////////////////////////////////////////////////////}